   Copyright (C) 1993, 1995 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the entire resulting derived work is distributed under the terms
of a permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.

Removing a problem category
---------------------------

   To remove a category from the database:

  1. Remove the Problem Reports from the subdirectories corresponding
     to the categories you wish to remove, or assign the PRs to new
     categories.  All PRs for a given category reside in
     `GNATS_ROOT/CATEGORY'.  Make sure you do this for each category
     you wish to remove.

  2. Run `rmcat' using

          rmcat CATEGORY [ CATEGORY... ]

     where CATEGORY is the category you wish to remove.  You can
     specify as many categories as you wish as long as each category
     has no PRs associated with it.  `rmcat' removes the directory under
     GNATS_ROOT where the Problem Reports for that category had been
     stored.  `rmcat' also deletes the category from the list of valid
     categories for both your locally installed `send-pr' and for the
     `send-pr' distribution template in `PREFIX/lib/gnats/dist' (see
     Where GNATS lives).

   *Note:* `rmcat' does not update the categories list for other
machines on your network which have `send-pr' installed.  See
Managing GNATS over a network.

   It is also important to note that only your local `send-pr' has
access to this new information; any copies of `send-pr' which you have
distributed to outside submitters now have outdated category lists.
You must either contact your submitters and instruct them to update
their copy of the categories list, which they installed in
`PREFIX/lib/gnats/SUPPORT-SITE' (*Note:* the value for PREFIX may be
different from yours) from the distribution you provided, or you must
build another distribution of `send-pr' with this new information and
redistribute it (see Configuring `send-pr' for the outside world).

Regenerating the index
----------------------

   If your `index' file becomes corrupted, or if you need a copy of the
current index for some reason, use

     gen-index [ -n | --numeric ]
               [ -d DIRECTORY | --directory=DIRECTORY ]
     	  [ -c FILENAME | --catfile=FILENAME ]
               [ -o FILENAME | --outfile=FILENAME ]
               [ -h | --help] [ -V | --version ]

With no options, `gen-index' generates an index that is ordered the
same as the order of the categories as they appear in the `categories'
file, and prints it to standard output.  The options are:

`-n'
`--numeric'
     Sorts index entries numerically.

`-d DIRECTORY'
`--directory=DIRECTORY'
     Uses DIRECTORY as the directory containing the database, by
     default GNATS_ROOT (see Where GNATS lives).

`-o FILENAME'
`--outfile=FILENAME'
     Places output in FILENAME rather than sending it to standard
     output.

`-c FILENAME'
`--catfile=FILENAME'
     Point to FILENAME, the file listing the valid categories.

`-h'
`--help'
     Prints the usage for `gen-index'.

`-V'
`--version'
     Prints the version number for `gen-index'.

Configuring `send-pr' for the outside world
-------------------------------------------

   Now that GNATS is up and running on your system, you probably want
to distribute `send-pr' to all your friends, relatives, enemies, etc.
so they can more easily submit bugs to your organization.  To do this,
create a new directory DIST-DIRECTORY to hold the distribution.  Then
run the program

     mkdist --release=RELEASE DIST-DIRECTORY

This populates DIST-DIRECTORY with a full distribution of the program
`send-pr', including a `Makefile' and all the `send-pr' documentation.
You can then simply package up this directory and send it to your bug
report submitters.  For example, when logged in as `gnats' you can do
the following:

     mkdir new-dist
     mkdist --release=tools-1.2 new-dist
     tar cvf send-pr.tar new-dist

   This creates a file called `send-pr.tar' which contains a full
distribution of `send-pr' customized for your site, with a default
release number of `tools-1.2'.  You can then place this onto a disk or
tape and send it to your submitters, or instruct your submitters to
download it using `ftp'.

   If you only have one submitter, you can set the Submitter ID in the
send-pr script by specifying the -submitter option to mkdist.  If you
do this, the submitter will not have to run install-sid.

Internal utilities
==================

   These tools are used internally by GNATS.  You should never need to
run these by hand; however, a complete understanding may help you locate
problems with the GNATS tools or with your local implementation.

Handling incoming traffic
-------------------------

   The program `queue-pr' handles traffic coming into GNATS.
`queue-pr' queues incoming Problem Reports in the directory
`GNATS_ROOT/gnats-queue', and then periodically (via `cron') passes
them on to `file-pr' to be filed in the GNATS database.  See
Installing GNATS.

   The usage for `queue-pr' is as follows:

     queue-pr [ -q | --queue ] [ -r | --run ]
              [ -f FILENAME | --file=FILENAME ]
              [ -d DIRECTORY | --directory=DIRECTORY ]

   One of `-q' or `-r' (or their longer-named counterparts) must be
present upon each call to `queue-pr'.  These options provide different
functions, as described below.

`-q'
`--queue'
     Accepts standard input as an incoming mail message, placing this
     message in an incrementally numbered file in the `gnats-queue'
     directory under `GNATS_ROOT' (see Where GNATS lives).

`-r'
`--run'
     Redirects files in the `gnats-queue' directory into the program
     `file-pr' one by one.

`-f FILENAME'
`--file=FILENAME'
     Used with `-q' (or `--queue'), accepts the file denoted by
     FILENAME as input rather than reading from standard input.

`-d DIRECTORY'
`--directory=DIRECTORY'
     Resets the default DIRECTORY value, which is by default
     `GNATS_ROOT/gnats-queue'.  When `-d DIRECTORY' is used in
     conjunction with the `-q' (or `--queue') option, `queue-pr' files
     incoming messages into DIRECTORY rather than the `gnats-queue'
     directory.  When `-d DIRECTORY' is used in conjunction with the
     `-r' (or `--run') option, `queue-pr' redirects into `file-pr'
     files from DIRECTORY rather than from the `gnats-queue' directory.

Processing incoming traffic
---------------------------

   `queue-pr' hands off queued Problem Reports to `file-pr' one at a
time.  `file-pr' checks each Problem Report for correct information in
its fields (particularly a correct `>Category:'), assigns it an
identification number, and files it in the database under the
appropriate category.

   If the `>Category:' field does not contain a valid category value
(i.e., matching a line in the `categories' file; see The `categories' file),
the PR is given a `>Category:' value of `pending'
and is placed in the `pending' directory.  The GNATS administrator is
notified of the unplaceable PR.

   `file-pr' assigns the Problem Report an identification number, files
it in the GNATS database (under `pending', if the `>Category:' field
contains an invalid category), and sends acknowledgements to
appropriate parties.  The person responsible for that category of
problem (see The `categories' file) and the person
responsible for the submitter site where the PR originated (see The `submitters' file)
receive a copy of the PR in its
entirety.  Optionally, the originator of the PR receives an
acknowledgement that the PR arrived and was filed (see Changing your local configuration).

   The usage for `file-pr' is as follows:

     file-pr [ -f FILENAME | --file=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORYb ]
     	[ -D | --debug ] [ -h | --help ] [ -V | --version ]

   `file-pr' requires no options in order to operate, and takes input
from standard input (normally, the output of `queue-pr -r') unless
otherwise specified.  The options include:

`-f FILENAME'
`--filename=FILENAME'
     Uses FILENAME as input rather than standard input.

`-d DIRECTORY'
`--directory=DIRECTORY'
     Performs refiling operations in DIRECTORY rather than in
     `GNATS_ROOT'.

`-D'
`--debug'
     Give debugging output while `file-pr' is running.

`-h'
`--help'
     Prints the usage for `file-pr'.

`-V'
`--version'
     Prints the version number for `file-pr'.

Timely reminders
----------------

   `at-pr' creates a queued job using `at' which, after an allotted
"response time" is past, checks the PR to see if its state has changed
from `open'.

   The `submitters' file contains the response time for each
`>Submitter-Id:' (see The `submitters' file).  The time
is determined in "business hours", which are defined by default as
8:00am to 5:00pm Monday through Friday, local time.  These hours are
defined in the `config' file (see The `config' file).

   If the PR is still open after the requisite time period has passed,
`at-pr' sends a reminder to the GNATS administrator, to the maintainer
responsible for that submitter, and to the maintainer responsible for
the PR with the following message:

     To: SUBMITTER-CONTACT RESPONSIBLE GNATS-ADMIN
     Subject: PR GNATS-ID not analyzed in #HOURS hours

     PR GNATS-ID was not analyzed within the acknowledgment period
     of #HOURS business hours.  The pertinent information is:

      Submitter-Id: SUBMITTER
      Originator: FULL NAME OF THE SUBMITTER
      Synopsis: SYNOPSIS
      Person responsible for the PR: RESPONSIBLE

     --
     The GNU Problem Report Management System (GNATS)

The `edit-pr' driver
--------------------

   `pr-edit' does the background work for `edit-pr', including
error-checking and refiling newly edited Problem Reports and handling
file locks.  It can be called interactively, though it has no useable
editing interface.

   The usage for `pr-edit' is:

     pr-edit [ -l MAINTAINER --lock=MAINTAINER ]
             [ -u | --unlock ] [ -c | --check ] [ -F ]
     	[ -L | --lockdb ] [ -U | --unlockdb ]
             [ -f FILENAME | --filename=FILENAME ]
             [ -d DIRECTORY | --directory=DIRECTORY ]
             [ -h | --help ] [ -V | --version ]
             [ GNATS-ID ]

   A "lock" is placed on a Problem Report while the PR is being edited.
The lock is simply a file in the same directory as the PR, with the name
`GNATS-ID.lock', which contains the name of the maintainer who created
the lock.  MAINTAINER then "owns" the lock, and must remove it before
the PR can be locked again, even by the same MAINTAINER(1).  If a PR is
already locked when you attempt to edit it, `pr-edit' prints an error
message giving the name of the maintainer who is currently editing the
PR.

   If you do not specify GNATS-ID, `pr-edit' reads from standard input.
You must specify GNATS-ID for the functions which affect PR locks,
`--lock=MAINTAINER' and `--unlock'.

`-l MAINTAINER'
`--lock=MAINTAINER'
     Locks Problem Report GNATS-ID, failing (and returning an error
     message) if GNATS-ID is already locked, or if GNATS-ID does not
     exist.  `pr-edit' requires that you specify GNATS-ID when using
     this option.

`-u'
`--unlock'
     Unlocks Problem Report GNATS-ID.  `pr-edit' requires that you
     specify GNATS-ID when using this option.  You must own a file lock
     to remove it.

`-L'
`--lockdb'
     Locks the GNATS database as a whole.  This will prevent any
     modification to any part of the system while it's locked.

`-U'
`--unlockdb'
     Unlocks the GNATS database as a whole, allowing modification of its
     files.

`-c'
`--check'
     Checks the Problem Report in GNATS-ID (or standard input, if
     GNATS-ID is not present) for correct information in its ENUMERATED
     fields.  `pr-edit' complains about any bogus information in the
     Problem Report.

`-F'
     Forces the PR to be submitted to the database, even if there is no
     current index entry for it (i.e., even if the PR did not exist in
     the database previously).

     *Warning: using this option may corrupt your index.*  If you use
     it, be sure you know what you are doing.

`-f FILENAME'
`--filename=FILENAME'
     Reads FILENAME rather than standard input.

`-d DIRECTORY'
`--directory=DIRECTORY'
     Resets the operating directory (`GNATS_ROOT').

`-h'
`--help'
     Prints the usage for `pr-edit'.

`-V'
`--version'
     Prints the version number for `pr-edit'.

   ---------- Footnotes ----------

   (1) This approach may seem heavy-handed, but it ensures that changes
are not overwritten.

Address retrieval
-----------------

   Returns an electronic mail address when given a valid "nametag", as
it appears in the `responsible' file (see The `responsible' file).
If NAMETAG is not valid, `pr-addr' will tell the user
that it could not find the requested address.

   Usage is simply:

     pr-addr NAME

Installing GNATS
****************

   See Where the tools and utilities reside.

   There are several steps you need to follow to fully configure and
install GNATS on your system.  You need `root' access in order to
create a new account for `gnats' and to install the GNATS utilities.
You may need `root' access on some systems in order to set mail aliases
in place and to allow this new account access to `cron' and `at'.

   If you are updating an older version of GNATS rather than installing
from scratch, see Upgrading from older versions.

   To build GNATS, you must:

   * Run `configure', with correct options if the defaults are
     unsuitable for your site.  See Configuring and compiling the software.
     Default installation locations are
     in Where GNATS lives.

   * Compile the GNATS programs on your system.  See Configuring and compiling the software.

   * Install the GNATS tools and utilities locally, and install the user
     tools on every machine in your local network.  See Installing the utilities.

   * Set up mail aliases for GNATS.  See Setting up mail aliases.

   * Install the GNATS user tools (`query-pr', `nquery-pr', `edit-pr',
     `send-pr') around your network.  See Installing the user tools.

   * Install the GNATS daemon `gnatsd'.

   * Update the local configuration files

          config      categories  submitters  responsible  gnatsd.conf

     in `GNATS_ROOT/gnats-adm'.  See Changing your local configuration.

   * Create a distribution of `send-pr' for submitters outside your
     organization.  See Configuring `send-pr' for the outside world.

Configuring and compiling the software
======================================

  1. First, unpack your distribution.  We provide source code in a `tar'
     file which was compressed using `gzip'.  The code can be extracted
     into a directory UNPACKDIR using

          mkdir UNPACKDIR
          cd UNPACKDIR
          tar zxvf gnats-3.101.tar.z

     The sources reside in a directory called `gnats-3.101' when
     unpacked.  We call this the "top level" of the source directory,
     or "srcdir".  The sources for the GNATS tools are in the
     subdirectory `gnats-3.101/gnats/*'.  Lists of files included in
     the distribution are in each directory in the file `MANIFEST'.

  2. You may wish to alter the installation directory for the Emacs lisp
     files.  If your Emacs lisp library is not in
     `PREFIX/lib/emacs/lisp', edit the files

          SRCDIR/gnats/Makefile.in   *and*
          SRCDIR/send-pr/Makefile.in

     Change the variable `lispdir' from `$(datadir)/emacs/lisp' to the
     directory containing your Emacs lisp library.  For information on
     PREFIX, see PREFIX.

  3. Run `configure'.  You can nearly always run `configure' with the
     command

          ./configure --with-full-gnats

     and the "Right Thing" happens:

        * GNATS is configured in the same directory you unpacked it in;

        * when built, GNATS runs on the machine you're building it on;

        * when installed, files are installed under `/usr/local' (see
          Where GNATS lives).

        * GNATS operates by default behavior (see Default behavior).

     The full usage for `configure' is:

          configure [ --with-full-gnats ]
                    [ --prefix=PREFIX ]
                    [ --exec-prefix=EXEC-PREFIX ]
                    [ --with-gnats-root=GNATS_ROOT ]
                    [ --with-gnats-server=HOSTNAME ]
                    [ --with-gnats-service=SERVICE-NAME ]
                    [ --with-gnats-user=USERNAME ]
                    [ --with-gnats-port=PORT-NUMBER ]
                    [ --verbose ]

    `--with-full-gnats'
          All programs are to be built; this includes the user
          utilities, the administrative utilities, and the internal
          utilities.  Use this when configuring the utilities for the
          machine where GNATS is to run.  Omit it when building only
          the user utilities for other machines on your network; see
          Installing the user tools.

    `--prefix=PREFIX'
          All host-independent programs and files are to be installed
          under PREFIX.  (Host-dependent programs and files are also
          installed in PREFIX by default.)  The default for PREFIX is
          `/usr/local'.  See Where GNATS lives.

    `--exec-prefix=EXEC-PREFIX'
          All host-dependent programs and files are to be installed
          under EXEC-PREFIX.  The default for EXEC-PREFIX is PREFIX.
          See Where GNATS lives.

    `--with-gnats-root=GNATS_ROOT'
          The database and its data files are to be installed into
          GNATS_ROOT.  The default for GNATS_ROOT is
          `PREFIX/lib/gnats/gnats-db'.  See Where GNATS lives.

    `--with-gnats-root=hostname'
          FIXME

    `--with-gnats-root=SERVICE-NAME'
          FIXME

    `--with-gnats-user=USERNAME'
          FIXME

    `--with-gnats-port=PORT-NUMBER'
          FIXME

    `--verbose'
          Give verbose output while `configure' runs.

     See Using `configure' (configure).

     You can build GNATS in a different directory (OBJDIR) from the
     source code by calling the `configure' program from the new
     directory, as in

          mkdir OBJDIR
          cd OBJDIR
          SRCDIR/configure ...
          make all

     By default, `configure' compiles the programs in the same directory
     as the sources (SRCDIR).  Emacs lisp files are byte-compiled if
     `make' can find Emacs on your local system.

  4. Run

          make all info

     from the directory where `configure' created a `Makefile'.  (This
     may not be the same directory as the source directory.)  These
     targets indicate:

    `all'
          Compile all programs

    `info'
          Create `info' files using `makeinfo'.

Installing the utilities
========================

   The following steps are necessary for a complete installation.  You
may need `root' access for these.

  1. Install the utilities by invoking

          make install install-info

     These targets indicate:

    `install'
          Installs all programs into their configured locations (see
          Where GNATS lives).

    `install-info'
          Installs `info' files into their configured locations (see
          Where GNATS lives).

     After you have installed GNATS, you can remove the object files
     with

          make clean

  2. Place the following lines in the file `default.el' in your Emacs
     lisp library, or instruct your local responsible parties to place
     the lines in their local editions of `.emacs':

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

     Emacs lisp files are byte-compiled if `make' can find Emacs on your
     local system.

  3. Create an account for a user named GNATS.  This user must have an
     entry in the file `/etc/passwd'.  The home directory for this
     account should be the same directory you specified for GNATS_ROOT
     in the file `Makefile.in'.  Also, the default `PATH' for this user
     should contain `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'.

  4. Allow the new user `gnats' access to `cron' and `at'.  To do this,
     add the name `gnats' to the files `cron.allow' and `at.allow',
     which normally reside in the directory `/var/spool/cron'.  If
     these files do not exist, make sure `gnats' does not appear in
     either of the files `cron.deny' and `at.deny' (in the same
     directory).

     For the following steps, log in as `gnats'.

        * Edit the files `categories', `responsible', and `submitters'
          in the directory `GNATS_ROOT/gnats-adm' (see Changing your local configuration)
          to reflect your
          local needs.  Be sure to run `mkcat' after you update the
          `categories' file (see Adding a new problem category).
          *Note:* these templates are not installed if they
          already exist, i.e. if you are upgrading.  See Upgrading from older versions.

        * If you wish to install the GNATS user tools on other machines
          on your network, see Installing the user tools.

  5. Create a `crontab' entry that periodically runs the program
     `queue-pr' with the `--run' option.  For example, to run
     `queue-pr --run' every ten minutes, create a file called `.mycron'
     in the home directory of the user `gnats' which contains the line:

          0,10,20,30,40,50 * * * * EXEC-PREFIX/lib/gnats/queue-pr --run

     (Specify the full path name for `queue-pr'.)  Then run

          crontab .mycron

     See the `man' pages for `cron' and `crontab' for details on using
     `cron'.

Setting up mail aliases
=======================

   The following mail aliases must be placed in the file `/etc/aliases'
on the same machine where the GNATS tools are installed.  You may need
`root' access to add these aliases.

   * Create an alias for the GNATS administrator.  This address should
     point to the address of the person in charge of administrating
     GNATS:

          gnats-admin:  ADDRESS

   * Create an alias to redirect incoming Problem Reports.  This alias
     should redirect incoming mail via a "pipe" to the program
     `queue-pr -q'.  For example, if Problem Reports coming to your
     site are to arrive at the address `bugs@your.company.com', create
     an alias to the effect of:

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"

     This places incoming Problem Reports in `GNATS_ROOT/gnats-queue'.

   * Create an alias for your site. This alias should be the same
     nametag indicated by the variable `GNATS_SITE' in the file
     `GNATS_ROOT/gnats-adm/config' (see The `config' file),
     with an added suffix `-gnats'.  This alias, `GNATS_SITE-gnats',
     should point toward the local submission address.  For instance,
     if your site is Tofu Technologies, the presence of GNATS on your
     SITE would be aliased as the following (the previous example is
     also shown):

          bugs:  "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          tofu-gnats: bugs

     The report submission utility `send-pr' automatically appends the
     `-gnats' to any arguments you specify (see Submitting Problem Reports).
     The `send-pr' which was installed when you
     typed `make install' has a default argument of GNATS_SITE, your
     site, so that when your local users simply type `send-pr' mail is
     sent to your local GNATS.  Part of the installation process a
     Submitter Site follows when installing `send-pr' is to set up an
     alias for the Support Site from whom this submitter received
     `send-pr'.  In other words, anyone you distribute `send-pr' to is
     instructed to make an alias

          tofu-gnats: bugs@tofu.com

   * You may also wish to forward a copy of each incoming Problem
     Report to a log.  This can be accomplished with something like:

          bug-q: "| EXEC-PREFIX/lib/gnats/queue-pr -q"
          bug-log:  GNATS_ROOT/gnats-adm/bugs.log
          bugs:      bug-q, bug-log

     This configuration archives incoming Problem Reports in the file
     `GNATS_ROOT/gnats-adm/bug.log', and also feeds them to the program
     `queue-pr'.  (Remember, `bug.log' needs to be world-writable, and
     should be pruned regularly; see GNATS Administration.)

   * If you want your users to be able to query the database by mail,
     use the following alias:

          query-pr: "| EXEC-PREFIX/lib/gnats/mail-query"

     The `mail-query' program uses `--restricted' to search on the
     database, and by default only searches for PRs that aren't closed
     (see Querying the database).

Installing the daemon
=====================

   By default, the daemon and clients are set to use port 1529.  Add
the line

     support		1529/tcp			# GNATS

to your `/etc/services' file.  If you want a different port, or a
different service name or port, configure GNATS with

     --with-gnats-service=SERVICENAME
     --with-gnats-port=PORTNUMBER

   In your `inetd.conf' file, add the line

     support	stream	tcp	nowait	gnats	/usr/local/lib/gnats/gnatsd gnatsd

adjusting the path accordingly.  To make inetd start spawning the GNATS
daemon when connected on that port, send it a hangup signal (`HUP').

   By default, the server for the GNATS daemon is assumed to be one
with the name of `gnats'.  If you'd like something else, use

     --with-gnats-server=HOSTNAME

   In the `gnats-adm' directory, you'll want to edit `gnatsd.conf'.  It
lists the hosts allowed to access your server.  Or, if you're using
Kerberos, it shows the sites that don't require Kerberos authentication.
The format is reserved for future revision; only the first field is
actually used:

     site.com::

The second field may be used for things like controlling what
categories, submitter-id'd PRs, etc., can be accessed from that site.
In the file that logs syslog messages (`/var/adm/messages', for
example) you'll find the notification of denied access.

Installing the user tools
=========================

   When you install the GNATS utilities, the user tools are installed
by default on the host machine.  If your machine is part of a network,
however, you may wish to install the user tools on each machine in the
network so that responsible parties on those machines can submit new
Problem Reports, query the database, and edit existing PRs.  To do this,
follow these steps *on each new host*.  You may need root access on
each machine.

  1. Make sure that the directory where GNATS resides is mounted to each
     system that will need access to it, so GNATS_ROOT will be the same
     for each host.  (You can do this with symbolic links as well.)

  2. Either mount the disk which contains your source directory, or
     make a copy of the GNATS source code tree in a separate directory
     on each system you wish to build on.

  3. Run `configure', *without* specifying `--with-full-gnats', and
     using the same argument (if any) for the option

          --with-gnats-root=GNATS_ROOT

     that you specified when building the GNATS utilites (see
     Configuring and compiling the software).  You
     may use different values for the other options to `configure'.
     Again, *do not* use `--with-full-gnats' at this point, as that
     creates all the GNATS programs.  Without this option, `configure'
     only instructs the resulting `Makefile' to create the user
     utilities.

     *You may need `root' access on each host for the following steps.*

  4. Create an account for a user named GNATS on the new host.  This
     user must have an entry in the file `/etc/passwd'.  The user ID for
     `gnats' must be the same as on the main GNATS host.

  5. Run

          make all info install install-info

     This builds and installs the `gnats' user tools `query-pr',
     `edit-pr', and `send-pr' on the new host, and installs them in
     `EXEC-PREFIX/bin' on the new host (*Note:* the value for
     EXEC-PREFIX on the new host may be different from the value you
     used when building the GNATS utilities; see EXEC-PREFIX).
     The programs `pr-edit' and `pr-addr' are installed
     into `EXEC-PREFIX/lib/gnats'.

     `info' files are created as well, and are installed into
     `PREFIX/info'.  The Elisp files `gnats.el' and `send-pr.el' (and
     possibly `gnats.elc' if `make' was able to compile them using
     Emacs) are installed into `PREFIX/lib/emacs/lisp' unless you
     change the `lispdir' variable in `Makefile.in' (see Configuring and compiling the software).

  6. Add the following lines to the file `default.el' in the Emacs lisp
     repository on the new host, or instruct your responsible parties
     who use these hosts to add them to their `.emacs' files:

          (autoload 'edit-pr "gnats"
             "Command to edit a problem report." t)
          (autoload 'view-pr "gnats"
             "Command to view a problem report." t)
          (autoload 'unlock-pr "gnats"
             "Unlock a problem report." t)
          (autoload 'query-pr "gnats"
             "Command to query information about problem reports." t)
          (autoload 'send-pr-mode "send-pr"
             "Major mode for sending problem reports." t)
          (autoload 'send-pr "send-pr"
             "Command to create and send a problem report." t)

  7. Copy the file `PREFIX/lib/gnats/SITE' from the original host to
     the new host (which may have a different value for PREFIX).  This
     is the list of valid categories that `send-pr' uses (see Where GNATS lives).
     SITE is your local site, the value of
     `GNATS_SITE' in the `config' file (see The `config' file).

Upgrading from older versions
=============================

   If you are upgrading from a previous release of GNATS, you probably
do not want to delete your current configuration files or your current
database.  The new GNATS can be installed around the older version.

   You need to:

   * Specify your current GNATS_ROOT on the command line to `configure'
     when you build the new tools, with

          configure --with-full-gnats --with-gnats-root=GNATS_ROOT

     (see Configuring and compiling the software.)

   * Remove the directory `gnats-bin' from GNATS_ROOT; it is no longer
     used.

   * Update your current mail aliases to reflect that `queue-pr' now
     resides in `EXEC-PREFIX/lib/gnats' rather than
     `GNATS_ROOT/gnats-bin' (see Where GNATS lives).

   * Change the default `PATH' for the `gnats' user to search the
     directories `EXEC-PREFIX/bin' and `EXEC-PREFIX/lib/gnats'.

   * Reinstall the GNATS user tools on all other hosts on your network
     (see Installing the user tools).

   * Redistribute `send-pr' to your Submitter Sites (see Configuring `send-pr' for the outside world).
     This is not absolutely
     necessary, as GNATS can read Problem Reports generated by older
     versions of `send-pr'.  It should be done eventually, however, as
     `send-pr' is improved over older verisons.

Where GNATS lives
*****************

   We use a few conventions when referring to the installation structure
GNATS uses.  These values are adjustable when you build and install
GNATS (see Installing GNATS).

PREFIX
======

   PREFIX corresponds to the variable `prefix' for `configure', which
passes it on to the `Makefile' it creates.  PREFIX sets the root
installation directory for "host-independent" files as follows:

libraries
     `PREFIX/lib'
`man' pages
     `PREFIX/man'

`info' documents
     `PREFIX/info'

`include' files
     `PREFIX/include'

*etc...*
   The default value for PREFIX is `/usr/local', which can be changed
on the command line to `configure' using

     configure --prefix=PREFIX ...

See Configuring and compiling the software.

EXEC-PREFIX
===========

   EXEC-PREFIX corresponds to the variable `exec_prefix' for
`configure', which passes it on to the `Makefile' it creates.
EXEC-PREFIX sets the root installation for "host-dependent" files as
follows:

binary tools
     `EXEC-PREFIX/bin'

binary support utilities
     `EXEC-PREFIX/lib/gnats'

compiled libraries
     `EXEC-PREFIX/lib'
*etc...*
   Since most installations are not intended to be distributed around a
network, the default value for EXEC-PREFIX is the value of `prefix',
i.e., `/usr/local'.  However, using EXEC-PREFIX saves space when you
are installing a package on several different platforms for which many
files are identical; rather than duplicate them for each host, these
files can be shared in a common repository, and you can use symbolic
links on each host to find the host-dependent files.  *It is not
necessary to use this paradigm when building the GNATS tools*.  See
Configuring and compiling the software.

   Use EXEC-PREFIX in conjunction with PREFIX to share host-independent
files, like libraries and `info' documents.  For example:

        *for each host:*
     configure --prefix=/usr/gnu --exec-prefix=/usr/gnu/H-HOST
     make all install ...

Using this paradigm, all host-dependent binary files are installed into
`/usr/gnu/H-HOST/bin', while files which do not depend on the host type
for which they were configured are installed into `/usr/gnu'.

   You can then use a different symbolic link for `/usr/gnu' on each
host (`/usr' is usually specific to a particular machine; it is always
specific to a particular architecture).

       *on host-1:*
     ln -s /usr/gnu/H-HOST-1 /usr/gnu
       *on host-2:*
     ln -s /usr/gnu/H-HOST-2 /usr/gnu

To the end user, then, placing `/usr/gnu/bin' in her or his `PATH'
simply works transparently for each HOST type.

   You can change EXEC-PREFIX on the command line to `configure' using

     configure --exec-prefix=EXEC-PREFIX ...

   We recommend that you consult Using `configure' (configure),
before attempting this.  Again, *it is not
necessary to use this paradigm when building the GNATS tools*.

GNATS_ROOT
==========

   The location of the database and the administrative data files, by
default `PREFIX/lib/gnats/gnats-db'.  You can change this value on the
command line to `configure' using

     configure --with-gnats-root=GNATS_ROOT

Administrative data files reside in `GNATS_ROOT/gnats-adm'.  These
include `categories', `submitters', `responsible', and `config', as
well as two files generated and maintained by GNATS, `index' and
`current'.  See Changing your local configuration,
and Administrative data files.

Default installation locations
==============================

PREFIX
     defaults to `/usr/local'; change using `configure' (see
     Configuring and compiling the software).

EXEC-PREFIX
     defaults to PREFIX; change using `configure' (see Configuring and compiling the software).

GNATS_ROOT
     defaults to `PREFIX/lib/gnats/gnats-db'; change using `configure'
     (see Configuring and compiling the software).

GNATS installs tools, utilities, and files into the following locations.

`EXEC-PREFIX/bin'

    `send-pr'
          See Submitting Problem Reports.

    `edit-pr'
          See Editing existing Problem Reports.

    `query-pr'
          See Querying the database.

    `nquery-pr'
          See Querying the database over the network.

`EXEC-PREFIX/lib/gnats'

    `mkcat'
          See Adding a problem category.

    `rmcat'
          See Removing a problem category.

    `mkdist'
          See Configuring `send-pr' for the outside world.

    `gen-index'
          See Regenerating the index.

    `queue-pr'
          See Handling incoming traffic.

    `file-pr'
          See Processing incoming traffic.

    `at-pr'
          See Timely reminders.

    `pr-edit'
          See The `edit-pr' driver.

    `pr-addr'
          See Address retrieval.

    `libiberty.a'
          The GNU `libiberty' library.

`PREFIX/lib/gnats/dist'

    A packageable distribution of `send-pr'.
          See Configuring `send-pr' for the outside world.

`PREFIX/lib/gnats'

    SITE
          The local list of valid categories, used by `send-pr'; SITE
          is the value of `GNATS_SITE' (see The `config' file).

`PREFIX/lib/emacs/lisp'

    `gnats.el'
    `gnats.elc'
          The Emacs versions of the programs `query-pr', `edit-pr', and
          `view-pr'.  See Invoking the GNATS tools.
          To change this directory you must alter
          `Makefile.in'; see Configuring and compiling the software.

    `send-pr.el'
          The Emacs version of the program `send-pr'.  See Submitting Problem Reports.

`PREFIX/info'

    `gnats.info'
    `send-pr.info'
          The GNATS manuals, in a form readable by `info' (the GNU
          hypertext browser).  See Reading GNU Online Documentation (infoman).

`PREFIX/man/man1'
`PREFIX/man/man8'

    `man' pages for all the GNATS tools and utilities.
          See Invoking the GNATS tools.

`PREFIX/src'

    Source code for GNATS.

`PREFIX/sample'

    Example administrative files, including `categories',
          `submitters', `responsible', and `config'.  See Changing your local configuration.

`GNATS_ROOT'

    `gnats-adm'
          Administration and configuration data files.  The files
         `config'

         `categories'

         `submitters'

         `responsible'

         `gnatsd.conf'

         `index'
               (*This file is created by GNATS.*)

         `current'
               (*This file is created by GNATS.*)

          exist here.  See Changing your local configuration,
          and Administrative data files.

    `gnats-queue'
          Incoming Problem Reports are queued here until the next
          iteration of `queue-pr -r' (see Handling incoming traffic).

    `pending'
          Problem Reports which arrive without a valid category value
          are reassigned to the category `pending' and placed here
          pending intervention by the GNATS administrator.  See GNATS administration.

    `CATEGORY'
          Each valid category has a corresponding subdirectory in the
          database.  All Problem Reports associated with that category
          are kept in that subdirectory, along with lock files for PRs
          which are being edited.

Querying using regular expressions
**********************************

   GNATS uses GNU regular expression syntax with these settings:

     RE_SYNTAX_POSIX_EXTENDED | RE_BK_PLUS_QM & RE_DOT_NEWLINE

This means that parentheses (`(' and `)') and pipe symbols (`|') do not
need to be used with the escape symbol `\'.  The tokens `+' and `?' do
need the escape symbol, however.

   Unfortunately, we do not have room in this manual for an adequate
tutorial on regular expressions.  The following is a basic summary of
some regular expressions you might wish to use.

   See Regular Expression Syntax (regex),
for details on regular expression syntax.  Also see Syntax of Regular Expressions (emacs),
but beware that the syntax for
regular expressions in Emacs is slightly different.

   All search criteria options to `query-pr' rely on regular expression
syntax to construct their search patterns.  For example,

     query-pr --state=open

matches all PRs whose `>State:' values match with the regular
expression `open'.

   We can substitute the expression `o' for `open', according to GNU
regular expression syntax.  This matches all values of `>State:' which
begin with the letter `o'.

     query-pr --state=o

   is equivalent to

     query-pr --state=open

in this case, since the only value for `>State:' which matches the
expression `o' is `open'.  (Double quotes (`"') are used to protect the
asterix (`*') from the shell.)  `--state=o' also matches `o', `oswald',
and even `oooooo', but none of those values are valid states for a
Problem Report.

   Regular expression syntax considers a regexp token surrounded with
parentheses, as in `(REGEXP)', to be a "group".  This means that
`(ab)*' matches any number of contiguous instances of `ab', including
zero.  Matches include `', `ab', and `ababab'.

   Regular expression syntax considers a regexp token surrounded with
square brackets, as in `[REGEXP]', to be a "list".  This means that
`Char[(ley)(lene)(broiled)' matches any of the words `Charley',
`Charlene', or `Charbroiled' (case is significant; `charbroiled' is not
matched).

   Using groups and lists, we see that

     query-pr --category="gcc|gdb|gas"

is equivalent to

     query-pr --category="g(cc|db|as)"

and is also very similar to

     query-pr --category="g[cda]"

with the exception that this last search matches any values which begin
with `gc', `gd', or `ga'.

   The `.' character is known as a "wildcard".  `.' matches on any
single character.  `*' matches the previous character (except
newlines), list, or group any number of times, including zero.
Therefore, we can understand `.*' to mean "match zero or more instances
of any character."  For this reason, we never specify it at the end of
a regular expression, as that would be redundant.  The expression `o'
matches any instance of the letter `o' (followed by anything) at the
beginning of a line, while the expression `o.*' matches any instance of
the letter `o' at the beginning of a line followed by any number
(including zero) of any characters.

   We can also use the expression operator `|' to signify a logical
`OR', such that

     query-pr --state="o|a"

matches all `open' or `analyzed' Problem Reports.  (Double quotes (`"')
are used to protect the pipe symbol (`|') from the shell.)

   By the same token,(1) using

     query-pr --state=".*a"

matches all values for `>State:' which contain an `a'.  (These include
`analyzed' and `feedback'.)

   Another way to understand what wildcards do is to follow them on
their search for matching text.  By our syntax, `.*' matches any
character any number of times, including zero.  Therefore, `.*a'
searches for any group of characters which end with `a', ignoring the
rest of the field.  `.*a' matches `analyzed' (stopping at the first
`a') as well as `feedback'.

   *Note:* When using `--text' or `--multitext', you do not have to
specify the token `.*' at the beginning of TEXT to match the entire
field.  For the technically minded, this is because `--text' and
`--multitext' use `re_search' rather than `re_match'.  `re_match'
"anchors" the search at the beginning of the field, while `re_search'
does not anchor the search.

   For example, to search in the `>Description:' field for the text

     The defrobulator component returns a nil value.

we can use

     query-pr --multitext="defrobulator.*nil"

   To also match newlines, we have to include the expression `(.|^M)'
instead of just a dot (`.').  `(.|^M)' matches "any single character
except a newline (`.') *or* (`|') any newline (`^M')."  This means that
to search for the text

     The defrobulator component enters the bifrabulator routine
     and returns a nil value.

we must use

     query-pr --multitext="defrobulator(.|^M)*nil"

   To generate the newline character `^M', type the following depending
on your shell:

`csh'
     `*control*-V *control*-M'

`tcsh'
     `*control*-V *control*-J'

`sh (*or* bash)'
     Use the <RETURN> key, as in

          (.|
          )

   Again, see Regular Expression Syntax (regex),
for a much more complete discussion on regular
expression syntax.

   ---------- Footnotes ----------

   (1) No pun intended.